ContentConnect

ContentConnect allows editors to:

The corresponding functions are made available in both the SiteArchitect and the ContentCreator when the module is installed and configured.

Familiar FirstSpirit tools are used to maintain the content, meaning that editors who are already familiar with FirstSpirit do not require any additional knowledge. The content is made available to Commerce Cloud as part of a deployment so that it can be imported. Commerce Cloud then transfers the information to the live state.

As far as Commerce Cloud is concerned, this means there is no difference when it comes to delivering editorial content to the live state. Even if the FirstSpirit Server is shut down because of maintenance work, for example, this has no effect on Commerce Cloud.

FirstSpirit and Commerce Cloud are linked by an architecture made up of a range of components (see figure Architecture). These components are:

Figure 1. Architecture

The individual components always interact in accordance with the following schema:

Commerce Cloud thus represents the main component in this architecture. It delivers the content that has been created and/or maintained in FirstSpirit to the customer and provides all shop functions. There is only one loose link between the two systems; they primarily work in parallel with one another. If the FirstSpirit Server is shut down because of maintenance work, for example, this has no effect on Commerce Cloud.

The ContentConnect module enables editorial content to be maintained in FirstSpirit and this to then be transferred into Commerce Cloud via deployment. For this, the processing of content in both systems must be coordinated and be mutually compatible. The sub-chapters below describe the underlying concept used to achieve this compatibility.

1.3.1. Pages

Similar to FirstSpirit, the pages in Commerce Cloud are based on a structure of various components. To enable editorial content to be exchanged between both systems, these components must be coordinated.

Within the reference project ContentConnect Reference Project included in the delivery, the slots are represented by the content areas of a page template. Sections can be added to them - each one corresponds to an asset and, depending on the use cases, also has a slot configuration (see figure Page rendering). With the aid of these configurations, it is possible to define which target group can see the corresponding content, or for how long this remains visible, for example. Each slot configuration refers to exactly one asset.

As a result, assets can be generated with FirstSpirit, which are displayed via slots in a page.

Figure 2. Page rendering

1.3.2. Languages

Editorial content is maintained in different languages on both the Salesforce and the FirstSpirit side. For integration, an assignment between the languages of both systems is therefore required. For this, a convention has been adopted for the languages used in the reference project which relates to their abbreviation defined in FirstSpirit. This is oriented towards the existing languages in Salesforce and ensures every abbreviation is designated in accordance with the formula LANGUAGE CODE_COUNTRY CODE (see figure Languages). The language code corresponds to ISO 639 and the country code to ISO 3166.

Furthermore, in the project it is ensured that the FirstSpirit master language is assigned to the default language in Salesforce.

Figure 3. Languages

This information is presented in more detail in the Generation and Homepage chapters.

The ContentConnect module has the following technical requirements:

This section contains information which should be noted when using the ContentConnect module.

The ContentConnect module is the main component for connecting FirstSpirit and Commerce Cloud. It is extremely important for bidirectional data exchange between the FirstSpirit Server and Commerce Cloud.

The module provides a report in both SiteArchitect and ContentCreator, showing the product information obtained from Commerce Cloud. The module determines which data is required and transfers it to the report when an editor initiates a query prompting it to do so. The data that is returned can then be used again for creating and maintaining editorial content.

If a generation is performed once the content has been created, the module combines the content in the form of two XML files. The WebDAV module then transfers the files to the Commerce Cloud storage location. Commerce Cloud reads out the data from this location and transfers it to the live state.

The editorial content is created and edited in FirstSpirit. In this case, however, it is Commerce Cloud that transfers it to the live state. This means that the content has to be made available to Commerce Cloud. For this purpose, the ContentConnect module creates one XML file for the library and one for the slot configuration as part of a deployment. These files must be transferred to Commerce Cloud along with the referenced media.

This is the task of the WebDAV module, which acts as a link between FirstSpirit and Commerce Cloud and stores the data in the Commerce Cloud storage location. Commerce Cloud reads out the data from this location.

Within the reference project, JSTL is required to preview certain pages. The JSTL module enables this. However, the module only needs to be installed on the FirstSpirit Server if JSTL has not yet been integrated on the server in any other way.

The delivery includes three cartridges: int_firstspirit_cms_core, int_firstspirit_cms_mfra, and int_firstspirit_cms_sitegenesis.

The int_firstspirit_cms_core cartridge provides functions for importing the editorial content created in FirstSpirit into Commerce Cloud. For this, it contains the ContentSync pipeline, which in turn has two start nodes: LIBRARY and SLOT_CONFIGURATIONS (see figure Content Sync pipeline). The editorial content is imported via LIBRARY and the slot configurations via SLOT_CONFIGURATIONS accordingly. In both cases, the pipeline expects the Import File and Import Mode parameters. The pipeline should be called via job schedules. The cartridge defines suitable job step types. The cartridge also contains scripts which are used in the other two cartridges. The functions provided are used, for example, to map Commerce Cloud render templates on FirstSpirit page templates and thereby to make it possible to create category and product pages (see Product Page Template Uid, Category Page Template mappings, and category and product pages).

The int_firstspirit_cms_mfra cartridge overwrites a few templates from the MobileFirst reference architecture in order to enable a preview on the FirstSpirit side. In addition, the cartridge contains the RenderTemplate controller, which determines the Commerce Cloud render template for a specified product or a specified category. The controller uses the options of the MobileFirst reference architecture and draws on the functions of the int_firstspirit_cms_core cartridge.

For shops that are not based on the MobileFirst reference architecture, the int_firstspirit_cms_sitegenesis cartridge contains a corresponding implementation of the RenderTemplate controller.

Figure 4. Content Sync pipeline

The delivery includes three cartridges, which must be transferred to Commerce Cloud initially. Different methods for this are described in the Commerce Cloud documentation under Developing your storefront → Development components → Cartridges.

Next, the int_firstspirit_cms_core cartridge must be added to all sites which are to receive FirstSpirit content, as well as the business manager site. You can find relevant instructions in the Commerce Cloud documentation under Getting started → Getting started for developers → Registering your cartridge. Sites which are set up on the MobileFirst reference architecture and are maintained in FirstSpirit also require int_firstspirit_cms_mfra in their cartridge path. However, if a site is based on SiteGenesis, its cartridge path must include int_firstspirit_cms_sitegenesis.

To import the content and slot configurations generated by FirstSpirit into Commerce Cloud, a job schedule must be created in Commerce Cloud for each site. To do this, the int_firstspirit_cms_core cartridge defines two job step types:

Both have the mandatory parameters Import File and Import Mode:

The job schedule should use a workflow with two parallel flows. Each flow can then call one of the two job steps above.

In addition to the cartridges, in the metadata directory, the delivery also contains an export file for a job schedule, which can be used for reference purposes and which makes it easier to create the different job schedules.

After the import, further adaptations need to be made to the job schedule. The scope of both job flows must be set to the correct site. The Import File parameter must also be adapted in both job steps so that it contains the correct path.

In order to delete assets and slot configurations managed and deleted by FirstSpirit from Commerce Cloud too, the following steps must be taken:

Importing the user-defined system object attributes
For the persistence of time stamps assigned during generation, content cleanup uses the user-defined fsGenerationTime attribute as part of assets and slot configurations. This must initially be added to the system objects (content and slot configurations). To create the user-defined system object attributes, the Custom-Attributes-Metadata.xml export file must be imported from the metadata directory included in the delivery package. For this, the following steps must be performed in Salesforce Business Manager:

Generating search refinements for assets
For the newly created fsGenerationTime attribute, a Commerce Cloud Search Refinement is to be generated once the system object attributes have been imported. The Commerce Cloud documentation describes this under Merchandising your site → Content assets → Working with content assets → Creating content search refinements.

The OC API is used for aspects including reports and deployment. Therefore, the corresponding permissions must be set in Salesforce for the Client ID that is used.

The Client ID that is used requires permission to execute GET queries via the ShopAPI for the resources indicated below. These must be implemented in the global or site-specific context according to the use case.

In addition when using content cleanup:

Permissions are additionally required to execute GET, POST, and DELETE queries via the DataAPI for the resources indicated below. They are to be exclusively defined in the global context.

In addition when using content cleanup:

If, as an option, workflows are to be used for deleting library folders and folder assignments, permissions are then required to execute DELETE queries via the DataAPI for the following resources:

More detailed information on the OC API settings can be found in the Commerce Cloud documentation.

The ContentConnect delivery contains three modules that must be added to the FirstSpirit Server. To install the modules, open the ServerManager and select Server properties → Modules.

Figure 5. Module management in the server properties

The main panel contains a list of all the modules installed on the FirstSpirit Server. Click Install, then select the contentconnect-fsm-<version number>.fsm file provided first, followed by the WebDavDeployment-<version number>.fsm and jstl.fsm files. Each time you make a selection, click Open to confirm it. Once installation has been successfully completed, the folders ContentConnect, WebDavDeployment, and JSTL are added to the list. Each of these must be given All permissions.

The process of installing the modules must be completed by adding the Apache Commons Codec, version 1.8. This is a library that the WebDAV module uses.

For this purpose you require the commons-codec-1.8-bin.zip archive, which you can download from the following URL: http://commons.apache.org/proper/commons-codec

Extract the file anywhere within your file system and separate the commons-codec-1.8.jar file. This jar file must be added to the FirstSpirit Server: To do this, open the directory for your FirstSpirit installation, switch to the shared → lib sub-folder and copy the jar file to this location.

To use the WebDAV server with https instead of http, it is not necessary to perform any additional configuration work. However, a local certificate authority managed by the company is normally used for https. The certificate in question, including the entire chain up to the certificate on the WebDAV server, must be made available to the FirstSpirit Server's JVM.

Using the command below, import the public root or intermediate certificates into a JKS file and select Yes in answer to the question whether the certificate is to be trusted. You must repeat this process for each certificate.

keytool -import -file cert1.crt -keystore truststore.jks -storepass changeit

Copy the Trust Store that is generated into the firstspirit5 → conf directory of your FirstSpirit Server and add the following lines to the file firstspirit5 → conf → fs-wrapper.conf.

wrapper.java.additional.100=-Djavax.net.ssl.trustStore=conf/truststore.jks
wrapper.java.additional.101=-Djavax.net.ssl.trustStorePassword=changeit
wrapper.java.additional.102=-Djavax.net.ssl.trustStoreType=JKS

If the WebDAV server is expecting mutual SSL authentication, you must use the following calls to create and sign a client certificate as a first step.

openssl genrsa -out private.key 2048
openssl req -new -key private.key -out request.csr

The file request.csr is sent to the certificate authority, which responds with the file cert.crt. The private key, the public certificate, and the certificate from the certificate authority must then be collected in a Key Store to be read by the JVM.

cd firstspirit5/conf
openssl pkcs12 -export -in public.crt -inkey private.key \
-out clientcert.p12 -CAfile authority.crt

If the certificate chain consists of one or more intermediate certificates, you can import them via keytool.

keytool -import -file intermediate1.crt -trustcacerts \
-keystore clientcert.p12 -storepass changeit

The Key Store can be transferred to the JVM of the FirstSpirit Server by adding the following lines to firstspirit5 → conf → fs-wrapper.conf.

wrapper.java.additional.103=-Djavax.net.ssl.keyStore=conf/clientcert.p12
wrapper.java.additional.104=-Djavax.net.ssl.keyStorePassword=changeit
wrapper.java.additional.105=-Djavax.net.ssl.keyStoreType=PKCS12

A part of the StarterPackage included in the delivery is the reference project ContentConnect Reference Project, which must be installed on the FirstSpirit Server. To do this, open the import dialog in the ServerManager via the menu item Project → Import and click the Local button to select the ContentConnectReferenceProject.tar.gz file from your local data system. Then assign a project name and description and confirm the import with Yes. After successful installation, the project is added to the list in the main panel (see figure Imported project in the ServerManager).

Figure 6. Imported project in the ServerManager

A project-specific configuration is required in order to use the ContentConnect module. It is set up using the project component, which is already added to the reference project supplied.

To configure the project component, open the ServerManager and select Project properties → Project components. A list of all existing project components is displayed in the main panel. Select the entry ContentConnect Project Configuration and click Configure to open the associated dialog (see figure Configuration dialog for the project component).

Figure 7. Configuration dialog for the project component

Two web components are required for the Preview and for ContentCreator and have already been added to the reference project supplied. Nevertheless, they still need to be installed on an active web server. To do this, open the ServerManager and select Project properties → Web components.

Inside the main panel, various tab pages are visible. Each tab page contains a list of the existing web components. The list contains the following entries both for the Preview as well the ContentCreator (see figure Web components in the project properties):

Select a Web server on both tab pages via the selection box and start the installation by clicking the Install button. After successful installation, a dialog opens, in which the activation of the Web server must be confirmed.

More detailed information on how to add web components is available in the FirstSpirit Documentation for Administrators.

Figure 9. Web components in the project properties

The ContentConnect Preview Filter determines the correct storefront URL for displaying a page in the FirstSpirit preview. This URL is used to download the HTML and substitute the slots it contains with the corresponding editorial content. To carry out these steps, the filter requires some information that can be configured via various parameters in the web.xml of the added web components (for the Preview as well as ContentCreator). This information relates to various aspects, which can be divided into three groups.

Storefront URL parameters

As previously described, the Preview Filter loads the HTML of a page from the storefront and substitutes the placeholders it contains with editorial content to enable the page to be viewed in the FirstSpirit preview. To do this, a project-specific storefront URL is required. As this is maintained in the project settings, the Preview Filter requires the associated input component to be specified for its query.

Storefront Crop Marks parameters

The placeholders included in the editorial content consist of a start as well as an end comment and have the format <!-- CMS-<IDENTIFIER>-START --> or <!-- CMS-<IDENTIFIER>-END --> by default. However, the use of individual affixes can be activated via a toggle in the project settings, which must be added if necessary. In this case, the default values are overwritten and specific prefixes and suffixes are used instead. In order to grant the Preview Filter access to this information, it requires the associated input components to be specified.

Storefront protection parameters

It is possible to protect the connection to Commerce Cloud via an authentication. This can be (de)activated in Salesforce and must be applied to FirstSpirit via the corresponding toggle in the project settings. If it is activated, the required access data must also be specified. The Preview Filter must be able to access this information and therefore requires the associated input components to be specified.

Storefront downloader parameters

In addition to the other parameters which are primarily used to determine the correct storefront URL, it must be possible to control the behavior of the Preview Filter while the HTML of the corresponding page is downloading. For this, it has different parameters, which can be maintained in the project settings. The Preview Filter must be able to access this information and therefore requires the associated input components to be specified.

Example

An example web.xml in which two parameters are configured could look as follows:

Example web.xml. 

<filter>
   <filter-name>ContentConnectPreviewFilter</filter-name>
   <filter-class>com.espirit.moddev.demandware.preview.PreviewFilter</filter-class>
   <init-param>
      <param-name>storefront.downloader.socketTimeout</param-name>
      <param-value>500</param-value>
   </init-param>
   <init-param>
      <param-name>storefront.downloader.retryCount</param-name>
      <param-value>5</param-value>
   </init-param>
</filter>

The reference project ContentConnect Reference Project has different sections, with which images can be integrated on the various pages. It should be possible for the editor to crop the images to a certain image section. This function is activated by specifying a resolution.

Specifying the resolution. 

$CMS_REF(st_picture, resolution:"RESOLUTION")$

For the reference project, the following resolutions are required: BANNER, SLIDE, GRID_ELEMENT_HIGH, GRID_ELEMENT_WIDE, GRID_ELEMENT_SQUARE, IMAGE_MAP, and TECHNOLOGY_IMAGE. They are already applied within the ServerManager in the Project properties → Resolutions area and specified in the corresponding areas in the sections.

Figure 10. Resolutions

To transfer the content created in FirstSpirit to the Commerce Cloud storage location, the reference project supplied has a schedule, which contains the actions specified below (see figure Generation schedule actions). A description of the individual actions is provided in the subsequent sub-chapters.

More information on creating a schedule is available in the FirstSpirit Documentation for Administrators.

Figure 11. Generation schedule actions

4.9.1. Initializing SFCC deployment

The first step is to initialize the deployment. This involves setting up content cleanup. While this is under way, a time stamp prior to the generation is created. This time stamp is used by the cleanup action in the last step of the schedule to delete outdated assets and slot configurations. It is for this reason that the schedule contains the action Salesforce Commerce Cloud Initializer:

Figure 12. Schedule action

To use content cleanup, the initialization must be the first action of the schedule. Otherwise this can lead to inconsistencies in the data inventory.

4.9.2. Content preparation - Full generation

To deploy the content that is relevant to Commerce Cloud, it must be determined from the project first. This requires a full generation to be carried out, generating all the referenced media in the correct resolution. The full generation also generates the XML collectors initialized in the project settings and fills them on the basis of the xmlCollector calls in the templates.

The schedule therefore has the generation action Content Preparation in whose Properties the following options are activated (see figure Content preparation action):

• Perform FullGeneration
• Clear generation directory beforehand
• Generate Media in the generation directory

The defined Prefix for absolute paths /firstspirit is required for the WebDAV deployment action.

It is only possible to use the WebDAV module in conjunction with the default URL creator. To generate the path, the entry Default URLs is therefore selected, which is absolutely essential at this point.

The template sets for all the languages present in the project are also selected on the Extended tab page. In addition, the variable dwre_xmlGeneration is added, which contains the value false. This is set to the value true in the subsequent XML Import File actions and ensures that the XML files for the slot configurations and assets are only created once the generation is complete. The XML template in the project controls the process of generating the XML file.

Figure 13. Content preparation action

4.9.3. XML import file - Partial generations

Commerce Cloud expects all data that is transferred to it to be in the form of XML files. For this reason, the information determined during the full generation must be read out of the XML collectors that are generated. In this case, the information must instead be written to an XML file that has to be created each time.

For each XML collector initialized in the project settings, the schedule provides another generation action. In contrast to the Content Preparation action, these are, however, partial generations. In their Properties, the option Execute partial generation for following start nodes is therefore activated. As a starting point, one of the page references based on the XML template is used (see figure Partial generation).

The variable dwre_xmlGeneration, which contains the value true, is also added to the Extended tab page for each of these actions. Together with the start node selected in each case, this ensures that the selected page reference is not generated until this point in time. This means that all the information required for creating the XML file will be available when this happens and it will not be possible for any gaps to appear. The XML template in the project controls the process of generating the XML file.

Figure 14. Partial generation

4.9.4. WebDAV deployment

Next, the XML files generated by means of the partial generations must be transferred to Commerce Cloud. They are published via a script action, for which the following parameters are defined in their Properties:

Figure 15. Properties

url

The URL specifies the host and the path on the WebDAV server. It always has the following structure:

https://<SUBDOMAIN INSTANCE>.demandware.net/on/demandware.servlet/webdav/Sites/Impex/…​/<PREFIX>/<SITE ID>

The path points to the location where the XML file in question is expected to be during the import. It must refer to an existing directory. Additionally, the prefix must be the same as the Prefix for absolute paths used in the full generation.

user

A technical user who is authorized to use the WebDAV interface is required in order to transfer the data. This user must have write permissions and must be specified by name here.

password

A password is also required for the user specified in the previous step.

The technical user is subject to the password conditions defined by Commerce Cloud, which require the password to be changed at least every quarter. The parameter value must be changed each time this is carried out.

mediaurl

The media folder generated during the generation process, and its content, must be transferred to a separate directory so that Commerce Cloud can perform the import. This directory is defined using the parameter mediaurl. The mediaurl always has the following structure:

http://<SUBDOMAIN INSTANCE>.demandware.net/on/demandware.servlet/webdav/Sites/Libraries/<SITE ID>/default/<PREFIX>

srcprefixdir

If only one particular directory is transferred to Commerce Cloud, it can be specified in relation to the root node of the generation directory using the optional parameter srcprefixdir. If the parameter is not defined, or no value is saved for it, the entire generation directory will be transferred.

purge

This parameter is optional and may only have the value true or false. If true is set, all the files and directories under the specified URL will be deleted before the transfer starts. If the parameter is set to false or no value at all, all the existing files and directories under the specified URL will be retained. New data will either be added or, in the case of existing data, overwritten.

The WebDAV deployment must not be executed in the event of an error.

4.9.5. Triggering an SFCC import job schedule

Following the publication of the created XML files via WebDAV deployment, the created job schedule is executed. In Salesforce, the job schedule triggers the import of the generated content and slot configurations into Commerce Cloud. The ContentConnect module provides the Salesforce Commerce Cloud Importer schedule action for this purpose:

Figure 16. Schedule action

The action loads a configuration dialog, in which two parameters must be defined in addition to a freely assignable name.

Figure 17. Schedule action parameters

Import Job ID

This field contains the ID of the created job schedule.

Timeout

The value in this field displays the time span in seconds, in which the status of the job schedule will be queried every second. If the job schedule has not completed in the specified time span, this schedule action is indicated as having an error. The default value is 10 seconds.

As the Salesforce Commerce Cloud Importer requires a successful WebDAV deployment, this too must not be executed in the event of an error.

4.9.6. Salesforce Commerce Cloud Cleanup

Once the created job schedule has been executed, content cleanup is executed. All outdated assets and slot configurations are queried by the OC API and then deleted. The ContentConnect module provides the Salesforce Commerce Cloud Cleanup schedule action for this purpose:

Figure 18. Schedule action

In addition to a freely assignable name for this schedule action, the associated configuration dialog contains the following parameters:

Figure 19. Schedule action parameters

Library Id

The ID of the Content Library must be entered in this field. In the case of a private library, the library ID corresponds to the site ID.

Cleanup Content Assets

This checkbox enables content cleanup for assets to be (de)activated.

Cleanup Slot Configurations

This checkbox enables content cleanup for slot configurations to be (de)activated.

To avoid inconsistencies in the data inventory or a loss of data, the Salesforce Commerce Cloud Cleanup action must correspond to the last action of the schedule. It is for the exact same reason that content cleanup requires that only full generations are executed with this action. In addition, the user is discouraged from creating duplicates within Commerce Cloud while executing the cleanup.

As the Salesforce Commerce Cloud Cleanup requires the job schedule to have been executed successfully and, therefore, content to be imported, this too must not be executed in the event of an error.

Content is released, deleted, and published by editors within the supplied reference project ContentConnect Reference Project via workflows. For this reason, it contains a publish workflow, as well as the BasicWorkflows, which can be used as an alternative to project-specific workflows.

Installing the BasicWorkflows module

Before using the workflows, you must install the BasicWorkflows module on the FirstSpirit Server and activate the web component. The necessary steps are the same as for installing the other modules and activating the associated web components. However, the web component for the BasicWorkflows is only needed on the ContentCreator tab page.

In addition, to use BasicWorkflows in the ContentCreator, the provided BasicWorkflows Status Providers must be selected in the Project properties → ContentCreator area within the ServerManager. In the reference project ContentConnect Reference Project, this setting has already been applied (see figure Element status provider).

Figure 20. Element status provider

In addition, in the Project properties → Options area, the Workflow for deleting elements is preselected. As a result, any action to delete elements within the project (Del button, delete icon) is executed via this workflow. The native (independent of a workflow) deletion of elements is therefore not available - not even for the administrator.

Templates

The BasicWorkflows and the workflow supplied with the StarterPackage require different templates. Usually, these need to be imported for the BasicWorkflows via the context menu in the FirstSpirit project used. However, they are already available in the reference project and importing the templates is therefore not necessary.

Permission assignment

In the final step, the workflows must be authorized in the individual stores so that they can be executed on FirstSpirit elements. To do this, select Extras → Change permissions from the context menu of the stores' root nodes to call up the permission assignment. This step has also already been carried out in the reference project and is therefore omitted.

You can find more detailed information on the BasicWorkflows in the associated documentation.

There is some essential project-specific information that needs to be entered for the connection between FirstSpirit and Commerce Cloud (see figure Project settings). It is entered using the project settings form and must be specified within the reference project.

Figure 21. Project settings

Additionally, the template is used to initialize two XML collectors and a Product Manager, which are used in the other page and section templates of the project. These page and section templates define which data is to be transferred to Commerce Cloud. During the generation process, the data is collected on the basis of these definitions and the XML collectors are filled.

While editorial content is being generated and maintained in FirstSpirit, Commerce Cloud determines the framework of a page. To present the preview of a page, the ContentConnect Preview Filter queries its current view in the Commerce Cloud Storefront and downloads the HTML. The slots it contains are uniquely labeled with HTML comments and are represented in FirstSpirit by the content areas of a page template.

Editor view
The editorial content is created and maintained in FirstSpirit. Editors have the standard tools available to them and do not require any additional knowledge. From the view of an editor, the content of both systems is automatically merged and displayed in the preview or in the ContentCreator.

Developer view
Within the reference project supplied, the slots from Salesforce are represented by the content areas of the page templates. Sections can be added to them - each one corresponds to an asset and, depending on the use case, also has a slot configuration. To display a page in the preview, the slots contained in the downloaded HTML are substituted by the editorial content.

For the substitution, all content relevant for the preview must be labeled with unique HTML comments. From a technical point of view, these can occur in every template but are only included in page templates in the reference project. Each consists of a start as well as an end comment and has the format <!-- CMS-<IDENTIFIER>-START --> or <!-- CMS-<IDENTIFIER>-END --> by default.

Should further substitutions be additionally required, specific regular expressions can be defined. These have their own syntax and always take the following form:

<!-- CMS-REGEX-PATTERN-START -->
   regex-match="<REGEX>"
   regex-value="<REPLACEMENT>"
<!-- CMS-REGEX-PATTERN-END -->

While the expression regex-match saves the regular expression, it is the expression regex-value that specifies the content which will substitute all regex matches in the document. Both expressions are to be summarized as an instruction by the HTML comments <!-- CMS-REGEX-PATTERN-START --> and <!-- CMS-REGEX-PATTERN-END -->.

With respect to the reference project, for example in the Preview Generation format template, this enables additional CSS to be integrated into each page template or any link on the Homepage to be substituted:

$-- Set Bootstrap CSS--$
<!-- CMS-REGEX-PATTERN-START -->
   regex-match="<\/head>"
   regex-value="$CMS_IF(#global.is("PREVIEW"))$$CMS_RENDER(template: "preview_css_additions")$$CMS_END_IF$</head>"
<!-- CMS-REGEX-PATTERN-END -->

$-- Change Homepage Reference --$
<!-- CMS-REGEX-PATTERN-START -->
   regex-match="href=("|').*.home[?]"
   regex-value="href="$CMS_REF(pageref:"homepage")$""
<!-- CMS-REGEX-PATTERN-END -->

ContentConnect preview proxy

If problems with cross-origin requests occur during the preview due to the same-origin policy of modern web servers, then these can be remedied by using the preview proxy included in the ContentConnect module.

In the supplied reference project, this is the case when loading the Font Awesome font via an integrated CSS file, for example. If the preview proxy is not used, a cross-origin request will be executed when the font is loaded, which will be blocked by the same-origin policy.

To manage the loading of the resources in question via the preview proxy and therefore avoid cross-origin requests, the Preview Generation format template includes the following regular expression. As a result, the configuration of the supplied web server does not need to be adapted.

Proxy integration. 

$-- Redirect to proxy --$
<!-- CMS-REGEX-PATTERN-START -->
   regex-match="[^"'(]*?\/on\/demandware\.static\/"
   $CMS_IF(#global.is("WEBEDIT"))$
      regex-value="/fs5webedit_$CMS_VALUE(#global.project.id)$/s=****/proxy/on/demandware.static/"
   $CMS_ELSE$
      regex-value="/fs5preview_$CMS_VALUE(#global.project.id)$/proxy/on/demandware.static/"
   $CMS_END_IF$
<!-- CMS-REGEX-PATTERN-END -->

Troubleshooting

ContentConnect supports developers when analyzing problems and errors in the preview, such as erroneous substitutions or poor response times while generating a preview.

Developers can add special parameters to the URL of a preview page in order to influence how the Preview Filter works and receive useful information as a result. The available URL extensions are /debugTimings=true and /debugCCFilter=true.

/debugTimings=true instructs the Preview Filter to write the execution times of its processing steps as a comment at the end of the HTML document. For this purpose, the Preview Filter measures the duration of the following actions:

If this parameter is specified, the Preview Filter generates the following output for the homepage of the reference project:

Output of the Preview Filter for the homepage with /debugTimings=true. 

<!--
*** TIMING STATS ***

LANGUAGE-DROPDOWN = 0ms
&lt;script [^&lt;]*?/dwux-init.js.*?&lt;/script&gt; = 0ms
[^&quot;'(]*/s/SiteGenesisGlobal_MF_SP/[^&quot;')]* = 53ms
Scanning for content replacement blocks = 1ms
CUSTOM-NAVIGATION-LEFT = 0ms
[^&quot;'(]*?/on/demandware.static/ = 113ms
(&lt;!-- dw.+?--&gt;) = 1ms
&lt;iframe.*?id=&quot;DW-SFToolkit&quot;&gt;.*?&lt;/iframe&gt; = 1ms
LANGUAGE-DROPDOWN-MOBILE = 0ms
&lt;a.*?sid=&quot;([^&quot;]*?)&quot; = 1ms
&lt;/head&gt; = 0ms
WILL-IGNORE-FOR-PREVIEW = 0ms
HOME-CATEGORIES = 0ms
href=(&quot;|').*.home[?] = 1ms
&lt;!-- Demandware Analytics(([sS]*)&lt;/script&gt;) = 1ms
&lt;!-- Demandware Active Data (([sS]*)&lt;/script&gt;) = 0ms
HOME-MAIN = 0ms
HOME-CC-OVERRIDE = 0ms

Total time = 172ms

-->

In addition, the Preview Filter logs some information in the FirstSpirit Server log if the /debugTimings=true parameter is specified.

/debugCCFilter=true means that the Preview Filter does not download the storefront, perform substitutions or present the result in the preview. The page actually generated by FirstSpirit is shown in the preview instead. The HTML therefore contains the substitution comments and specifications in addition to the editorial content. If this parameter is specified, the Preview Filter therefore generates the following output (in a shortened form) for the homepage of the reference project:

Output of the Preview Filter for the homepage with /debugCCFilter=true. 

<!-- CMS-HOME-MAIN-START -->
    [...]
<!-- CMS-HOME-MAIN-END -->

<!-- CMS-HOME-CATEGORIES-START -->
    [...]
<!-- CMS-HOME-CATEGORIES-END -->

[...]

<!-- CMS-REGEX-PATTERN-START -->
    regex-match="href=("|').*.home[?]"
    regex-value="href="/fs5webedit_90169/s=qgkM/preview/90169/site/EN_GB/current/90172/90361""
<!-- CMS-REGEX-PATTERN-END -->

[...]

Using these functions requires a preview page to be called up. The address of the preview page must have one of the parameters presented here added to it. There are various ways of doing this:

<!-- CMS-REGEX-PATTERN-START -->
    regex-match="href=("|').*.home[?]"
    regex-value="href="$CMS_REF(pageref:"homepage")$/debugCCFilter=true""
<!-- CMS-REGEX-PATTERN-END -->

In order to deploy editorial content, FirstSpirit generates two XML files, which contain content assets and slot configurations, and are transferred to the Commerce Cloud. The corresponding generation and deployment schedule has already been described. This description also explains that templates in their presentation channels populate XML collectors with content (content assets) and slot configurations. These collectors are initialized in the project settings. All content and configurations to be deployed must be written to the XML collectors. Otherwise, they will not be transferred.

One asset and one slot configuration are typically generated for each section, allowing for personalization at the section level. Content pages are the only exception. In this case, a total of precisely one content asset and one slot configuration are created.

This chapter explains how the content and configurations of the project are collected and the XML files generated.

$CMS_SET(set_xml_id, ps_dwAssetIdPrefix + "-" + #global.node.uid + "-" + #global.section.id)$
$CMS_SET(set_xml_id, set_xml_id.replaceAll("_","-"))$

$CMS_SET(void, ps_xmlCollector.useOrCreateContentNode(set_xml_id))$

$CMS_SET(void, ps_xmlCollector.addContentAttribute({
    "name":"display-name",
    "value":#global.node.getDisplayName(#global.language).toString(),
    "attributes":{
        "xml:lang":set_xml_lang
    }
}))$

$CMS_SET(void, ps_xmlCollector.addContentAttribute({
    "name":"searchable-flag",
    "value":"true"
}))$

$CMS_SET(void, ps_xmlCollector.addContentAttribute({
    "name":"online-flag",
    "value":"true"
}))$

$CMS_SET(void, ps_xmlCollector.addCustomAttribute({
    "id":"body",
    "cdata":set_xml_body.toString(),
    "attributes":{
        "xml:lang":set_xml_lang
    }
}))$

$CMS_SET(void, ps_xmlCollector.addFolderAttribute({
    "id":set_parent_id
}))$

$CMS_IF(!st_slotConfig.isEmpty)$
    $CMS_FOR(_slotConfig,st_slotConfig)$
        $CMS_VALUE(_slotConfig)$
    $CMS_END_FOR$
$CMS_END_IF$

$CMS_SET(void, ps_xmlCollectorContentSlot.addXml(null, set_slotConfig.toString(), null))$

The main menu is primarily used to navigate between the various category pages within the preview (see figure Navigation). The main menu is part of the HTML downloaded during the preview from the Commerce Cloud Storefront and is therefore predefined by Commerce Cloud.

Figure 22. Navigation

Editor view
The main menu allows the editor to switch between category pages. If an equivalent exists within FirstSpirit for a category page which has been called up, then the content of this page is shown. The editor is then able to edit the content originating from FirstSpirit. If no equivalent to the category page which has been called up exists within FirstSpirit, the original content obtained from Commerce Cloud is issued instead.

Developer view
To display a category page which exists in FirstSpirit to the editor, the navigation links in the main menu are redirected to a dispatcher page via a specific regular expression initially in the reference project.

Redirecting the navigation links. 

$-- Change Category Reference --$
<!-- CMS-REGEX-PATTERN-START -->
   regex-match="<a.*?\sid="([^"]*?)""
   regex-value="<a href="$CMS_REF(pageref:"preview_dispatcher")$?type=category&id=$1" id="$1""
<!-- CMS-REGEX-PATTERN-END -->

This regular expression, along with other specific regular expressions, forms part of the Preview Generation format template.

The preview dispatcher referenced in this expression is a technical page based on the page template with the same name. The preview dispatcher iterates over the content of the structure folder category_pages by using the FirstSpirit navigation function.

For each page found, the preview dispatcher memorizes the associated category, together with a corresponding reference to the page. As a result, for each call it can then decide whether a page exists in FirstSpirit for the requested category and forward accordingly.

If it was not possible to identify any pages created in FirstSpirit for a requested category, you are forwarded to a generic category preview page.

The homepage corresponds to the start page of the reference project supplied and is therefore displayed when the ContentCreator is first opened. Since its structure differs from that of the other content pages, it has its own template. This is referenced in the project just once.

Editor view
The homepage offers the editor three options for entering content:

The sections required for entering content are covered in more detail in the corresponding sub-chapters.

Developer view
The homepage template primarily defines how the page is displayed in the FirstSpirit preview, whereas assets are predominantly generated in the integrated sections. However, certain requirements for generation are managed in the form as well as in the HTML channel. The developer view must therefore take both aspects into account.

Preview
Commerce Cloud supports a range of page types. In order to display editorial content in the FirstSpirit preview or in ContentCreator, FirstSpirit must generate the correct storefront URL to query the corresponding page in Commerce Cloud.

The page type to be used for the FirstSpirit preview is defined in the Preview Page Type form field. As Home is the only parameter provided for the homepage, it is selected as a default value and the input component is hidden.

To determine the desired storefront URL, it must also be ensured that the language codes used in FirstSpirit and in Commerce Cloud match. This task is performed by the language_mapping format template, which is integrated in the HTML channel. If the language codes do not match, FirstSpirit is unable to determine the corresponding page for the preview.

The sections maintained for the homepage are output within unique HTML comments. These always consist of a start and an end expression and denote the individual content areas. Based on the comments, FirstSpirit substitutes the slots in the preview with editorial content.

<!-- CMS-HOME-MAIN-START -->
   $CMS_VALUE(#global.page.body("home_main"))$
   $CMS_RENDER(template:"empty_content_slot",label:"Home Main",body:"home_main")$
<!-- CMS-HOME-MAIN-END -->

<!-- CMS-HOME-CATEGORIES-START -->
   $CMS_VALUE(#global.page.body("home_categories"))$
   $CMS_RENDER(template:"empty_content_slot",label:"Home Categories",body:"home_categories")$
<!-- CMS-HOME-CATEGORIES-END -->

<!-- CMS-HOME-CC-OVERRIDE-START -->
   $CMS_RENDER(template: "cc_createsectionwe_api")$
<!-- CMS-HOME-CC-OVERRIDE-END -->

If a content area has no sections, FirstSpirit displays a gray-shaded area in the preview instead (see figure Empty slot). This shows the name of the content area and has a button which allows new sections to be generated in ContentCreator. The display of the gray area controls the empty_content_slot format template, while the function of the button is implemented in the cc_createsectionwe_api format template. It contains JavaScript, which may be integrated in the page only once.

Figure 23. Empty slot

Should further substitutions be required in addition to the exchange of slots, specific regular expressions can be defined. These have their own syntax and are summarized in the Preview Generation format template. It controls the generation of the preview and is referenced in all page templates of the reference project.

Generation
The assets created during the generation are filed in a folder structure in Salesforce. A corresponding folder is therefore defined for each page template in the reference project. The homepage form has the hidden SFCC Parent Folder field, whose value is assigned to the set_parent_id variable. It is evaluated in the integrated sections.

$CMS_SET(set_parent_id,pt_sfcc_parentFolder)$

A further requirement for generating assets is that the corresponding page must be marked as translated in FirstSpirit. If this is not the case, the generation is canceled.

$CMS_IF(!#global.preview && !#global.page.isTranslated)$
   $CMS_SET(#global.stopGenerate, true)$
$CMS_END_IF$

The content pages correspond to the standard pages of the project and are referenced multiple times. Unlike the homepage and the category and product pages, they play a special role as they generate just one asset for the entire page. All editorial content from the content page and the sections added to it are summarized in this asset.

Editor view
The content pages offer the editor three options for entering content:

The sections required for entering content are covered in more detail in the corresponding sub-chapters. As the text section is self-explanatory, this is not described specifically.

Developer view
Unlike for the remaining pages, the editorial content of the content page and its sections are summarized in a single asset. This asset is created in the HTML channel of the page template, which differentiates between the display of the page in the FirstSpirit preview and in the live state. The developer view must therefore take both aspects into account.

Preview

As the creation of the asset only affects generation, both developer views of the content page and the homepage are nearly identical with regard to the FirstSpirit preview.

The only discrepancy between both templates is in the configuration of the page type that is used, which is also defined in the hidden Preview Page Type form field for the content pages. In contrast to the homepage, it can assume different values in theory. For the reference project supplied, however, the Page parameter is required and is selected as the default value.

Furthermore, the content page has the hidden SFCC Context ID form field, in which a default content asset ID is saved. As a page still does not have an asset ID before generation, it is required to create the preview.

Generation

For generation, it is important to ensure firstly that the corresponding page is marked as translated in FirstSpirit. Only when this is the case is generation carried out and the asset for the content page is created.

$CMS_IF(!#global.preview && !#global.page.isTranslated)$
   $CMS_SET(#global.stopGenerate, true)$
$CMS_END_IF$

For this, the value of the hidden SFCC Parent Folder field is assigned to the set_parent_id variable initially. It specifies where the created asset is filed in the Salesforce folder structure.

$CMS_SET(set_parent_id,pt_sfcc_parentFolder)$

The variables are evaluated while the XML collector is populated, which is carried out subsequently. In the process, a new content node is created, to which the editorial content of the page, among other things, is added.

The ContentConnect module provides an individual report for products and categories in both SiteArchitect and ContentCreator. These reports are used to display the category and product information originating from Commerce Cloud, which can be used to create and maintain editorial content (see figure Reports).

Figure 24. Reports

The corresponding report can be used to create both product pages and category landing pages. To use this feature, you must define the templates on which these pages will be based, and where they are to be integrated into the structure, in the project component.

<CMS_INPUT_TEXT name="pt_storefrontUrlContextId" hidden="yes" useLanguages="no">
  <LANGINFOS>
    <LANGINFO lang="*" label="SFCC Context ID"/>
  </LANGINFOS>
</CMS_INPUT_TEXT>

With regard to its category or product page, an object in the report can adopt one of three states:

The three cases are displayed in different ways and described below.

Creating a category or product page

Objects for which a product page or a category landing page does not yet exist are identified in the report by a gray icon (see figure Creating a category or product page). If a page template has been defined in the project component, the button is displayed when you hover over them.

Figure 25. Creating a category or product page

Click on this button to open a dialog that is split into two sections and in which a page can be created for the corresponding object.

The top section of the dialog is the structure selection area; it is completed automatically and as such is always the same. Within the structure, the editor has the option to select the menu level at which to generate the new page. The corresponding input component may already have been preassigned. In this case, a structure folder will already have been defined in the configuration dialog of the project component. However, the editor is free to change this selection.

Unlike the structure selection area, the form area underneath is always project-specific. It shows the form for the page template specified in the project component. The rules defined in the template also apply here.

An example dialog is shown in the figure below:

Figure 26. Dialog for creating a category or product page

Click on Create to generate the page reference for the product page or category landing page at the previously selected menu level. The corresponding page is created in a specific folder in the Page Store.

If a script has also been specified in the project component, it is usually executed before and after the category or product page is created. The create_sfcc_item_wizard script included in the reference project supplied does, however, have a corresponding query, which is used to initiate the script, but only once the page has been created. It marks each created product page or category landing page as translated for all languages and saves its storefront ID in the form.

The following parameters are transferred to this script:

Once the process to generate the product page or category landing page and the execution of the script have been completed, the new page is called up automatically.

Calling up an existing category or product page
Objects for which a category or product page already exists are identified in the report by a green icon (see figure Product with product page). When you hover over them, the button is displayed. Click this button to call up the corresponding product page or category landing page.

Figure 27. Product with product page

Broken reference to a category or product page
Objects which have a product page or category landing page but its page reference or underlying page cannot be found are identified in the report by a red icon (see figure Broken object). When you hover over them, the button is displayed. Click on this button to open a dialog containing more information.

Figure 28. Broken object

Hidden categories
When the category report is called up, both visible as well as hidden categories are displayed by default. By removing the Include hidden categories check mark, the results list can be limited to include only visible categories:

Figure 29. Hiding hidden categories

$CMS_IF(!#global.preview && !#global.page.isTranslated || pt_storefrontUrlContextId.isEmpty)$
   $CMS_SET(#global.stopGenerate, true)$
$CMS_END_IF$

<CMS_INPUT_TOGGLE name="pt_hideNewPageDialogCC" hFill="yes" hidden="yes" singleLine="no">
  <LANGINFOS>
    <LANGINFO
      lang="*"
      label="Hide New Page Dialog in ContentCreator"
      description="Hide the dialog in the ContentCreator when creating a new landing page."
    />
  </LANGINFOS>
</CMS_INPUT_TOGGLE>

<CMS_INPUT_TOGGLE name="pt_hideNewPageDialogSA" hFill="yes" hidden="yes" singleLine="no">
  <LANGINFOS>
    <LANGINFO
      lang="*"
      label="Hide New Page Dialog in SiteArchitect"
      description="Hide the dialog in the SiteArchitect when creating a new landing page."
    />
  </LANGINFOS>
</CMS_INPUT_TOGGLE>

The header of a page allows a banner to be displayed in which either a static image or a slider can be integrated. Both variants each correspond to a section, which is available for the homepage and for normal content pages, as well as for category and product pages.

These are described in detail in the following sub-chapters.

Figure 30. Slider

$CMS_RENDER(template:"media_link",mediaref: st_picture,res:"SLIDE")$

5.7.2. Banner image

The banner image corresponds to a static image which is displayed in the header of a page.

Editor view
The static banner image is selected either via the media store or by uploading a new image. With the help of the standard FirstSpirit functionality, it can be cropped to the required image section.

In addition, the section offers editors the following further configuration options:

• Maintaining a one-line title
• Specifying a link to a product or category landing page
• Defining the size and banner display

Once a title has been entered, it will have a blue background and can be positioned left, right, or center on the banner image. In doing so, it should be specified whether the blue-shaded background is displayed on the left or right, only as a narrow strip, or over the entire height of the banner. In the central position, it generally spans the entire height. The input component for positioning only becomes visible when the title is entered and is otherwise hidden.

A link to a product or category landing page is specified by entering link text and the associated product or category ID. Both fields are automatically populated when a product or category is transferred from one of the two reports. As the link refers to the entire banner image, its link text is only used as a tooltip and is not displayed as a clickable link.

To define the size of the banner, the options Small and Big are available for editors.
The Small option minimizes the height of the banner and displays it only as a narrow strip. This could lead to a selected image being cropped at the bottom.
The Big option displays the banner without any height restrictions and also allows the editor to define a design.

For the design, the options none, up, and down are available. The none option results in no changes being made to the banner, while for the other two options, a white overlay is added to the upper left or lower right corner.

Figure 31. Banner image with 'up' design

Developer view
The HTML channel references the selected image and displays it together with the configured title and link, while taking into account the image section and layout defined by the editor. To crop the image, the BANNER resolution is required, which is already applied in the project properties of the reference project and must be specified in the HTML:

Specifying the resolution. 

$CMS_RENDER(template:"media_link",mediaref:st_picture,res:"BANNER")$

The st_picture input component has the upload=yes parameter, which allows the editor to upload new images, as well as to select an existing image from the media store.

The entire content is assigned to the set_sectionContent variable, which is required during generation of the homepage or a category or product page to populate the corresponding XML file. For a content page, however, the variable is only output.

As the image is referenced from the media store of the FirstSpirit project and is therefore not affected by substitution of Salesforce content, it does not have to be labeled with HTML tags.

In contrast to simple content pages, the homepage and category landing pages are able to display a group of three to five images via the grid container, each corresponding to a grid container element.

Figure 32. Grid container

Editor view
With the grid container, the editor is able to create a list of images, which can each be assigned a title as well as a link to a product, category, or content page. Depending on the configuration, three to five images are displayed from this list and can be individually cropped to the required image section. The images can originate from the media store or can be uploaded with the help of the input component.

The images are arranged according to a certain layout that is predetermined by the editor. The following seven options are available here.

Figure 33. Grid container - Layout options

Developer view
Within the HTML channel and based on the image section and layout chosen by the editor, the selected images are referenced and their configured titles and links displayed. Only the number of images corresponding to the layout are taken into account, and all other entries ignored.

To crop the images, the GRID_ELEMENT_SQUARE, GRID_ELEMENT_HIGH, and GRID_ELEMENT_WIDE resolutions are required. They are already applied in the project properties of the reference project and must be specified in the HTML:

Specifying the resolution. 

$CMS_REF(st_picture, resolution:"GRID_ELEMENT_SQUARE")$
$CMS_REF(st_picture, resolution:"GRID_ELEMENT_HIGH")$
$CMS_REF(st_picture, resolution:"GRID_ELEMENT_WIDE")$

The st_picture input component has the upload=yes parameter, which allows the editor to upload new images, as well as to select an existing image from the media store.

The content is assigned to the set_sectionContent variable, which is required during generation of the homepage or a category landing page to populate the corresponding XML file.

As the images are referenced from the FirstSpirit media store and there is no substitution of Salesforce content, they do not have to be labeled with HTML tags and are displayed in the preview in the usual way.

In addition to the grid container, products can be displayed in the form of hot spots. Each hot spot corresponds to a product link, which is defined on a single static image parallel to the other hot spots. When you click, a flyout opens for each hot spot, which includes the name, an image, and a description of the corresponding product.

The static image is selected and the hot spots are defined with the help of the Shop the look section template, which can only be added to the homepage and content pages.

Figure 34. Hot spots

Editor view
In addition to the static image, the editor can specify a title made up of maximum 20 characters, which can be positioned on the left, on the right or in the center on the image. The image can either be selected from the media store or uploaded via drag-and-drop on the Upload a picture button in the form. It can be cropped with the help of the familiar FirstSpirit functionality.

The editor can create any number of hot spots on the image by selecting an image section and defining a product link for this. The link expects a link text and a product ID. Both fields are automatically populated when a product is transferred from the product report. After the form has been saved, the created hot spots are displayed in the relevant location on the image and the link text corresponds to the displayed product name.

Developer view
The HTML channel initially references the selected image and displays it together with the title. The hot spots are then determined and positioned using the image sections specified by the editor. For each hot spot, the associated flyout is also created, which appears when the hot spot is clicked and automatically displays the corresponding product information.

The entire content is assigned to the set_sectionContent variable, which is required during generation of the homepage to populate the corresponding XML file. For a content page, however, the variable is only output.

As the image is referenced from the media store of the FirstSpirit project and is therefore not affected by substitution of Salesforce content, the content does not have to be labeled with HTML tags.

In contrast to the homepage and category landing pages, content pages have the option to display blog articles. Every blog article corresponds to a dataset of the Article data source and must first be generated by the editor.

With the aid of two table templates, they can be presented either in the form of an overview of all available blog articles or as a detail view of one single article. Both options are described in the sub-chapters below.

5.10.1. Article overview

The article overview presents all blog articles included in the project sorted by their creation date. In each case, the display is limited to the heading of an article plus the teaser and teaser image.

Figure 35. Article overview

Editor view
As the overview is generated automatically, the editor can only define the number of blog articles to be displayed as well as their distribution across one or more pages. It is configured using the familiar FirstSpirit functionality on the Data tab of the relevant page reference.

Apart from this, the editor has no access to the function other than to integrate the table template.

Developer view
The HTML channel of the table template determines the datasets of the Article data source and in each case outputs the heading, the teaser, and the teaser image of all blog articles one after the other. The individual articles are separated by a horizontal line and their headings match the link to the relevant detail page.

To link the detail page, its reference name must be known to the overview page. In the reference project, the reference name of the relevant page reference (magazine_article) was therefore permanently included to the template for the overview page. In individual scenarios, this is therefore to be adapted accordingly.

In addition, a navigation function is inserted in the first position before the list of blog articles. This enables users to browse through the blog articles if they are distributed across several pages. If all blog articles are presented on a single page, the navigation function is hidden.

A page in the reference project can also contain videos alongside purely textual information. Each video corresponds to a section, which provides different configuration options. The associated section template can only be added to content pages and category landing pages, not the homepage.

Editor view
To reference videos, editors can make use of the YouTube and Vimeo platforms. Both providers use a unique ID, which in each case forms part of the video URL:

The corresponding video for the page can be added using this ID. The video is displayed in the standard format of 16:9. The options 21:9, 4:3, or 1:1 are also available. Furthermore, the editor can define whether playback is started automatically and whether the video may be displayed in full screen mode.

Developer view
Within the HTML channel, the selected video is first referenced in direct relation to the defined video platform. For this, the display format as well as the different URL parameters are set and, in a final step, the correct video URL generated in accordance with the editor's configured settings in the form.

This content is assigned to the set_sectionContent variable, which is required during generation of a category landing page to populate the corresponding XML file. For a content page, however, the variable is only output.

As the embedded video does not come from Commerce Cloud, it does not have to be labeled with HTML tags. It is shown in the preview without substitution.

The reference project supplied uses English as the master language. It also has Italian, French, Japanese, and Chinese as project languages. To switch the view of a page to one of these languages, the project provides the option of changing languages in the preview. This is displayed either as a dropdown menu or within a menu as a list item, depending on the screen size used.

Figure 38. Changing the language

Editor view
Within the preview of the reference project, the change of language is displayed on the homepage, on content pages, and on category and product pages. This enables the editor to maintain editorial content on each page for all the languages contained within the project.

As the selection of existing languages is determined automatically based on the project languages and the display also cannot be influenced, the editor has no access to the function other than to simply use it.

Developer view
The change of language option is generated through the Language Dropdown format template and made available for use in the preview with the Preview Generation format template. This is displayed either as a dropdown menu or within a menu as a list item, depending on the screen size used (see figure Changing the language).

Both variants reference the Language Dropdown format template, which controls the display of variants via the showInMenu parameter to be transferred. As the change of language replaces all of the corresponding Salesforce content, both variants must be labeled with unique HTML comments.

Changing the language in the Preview Generation format template. 

$-- Preview Language Switch --$
<!-- CMS-LANGUAGE-DROPDOWN-START -->
   $CMS_RENDER(template:"sfcc_language_dropdown", mobile:false)$
<!-- CMS-LANGUAGE-DROPDOWN-END -->

<!-- CMS-LANGUAGE-DROPDOWN-MOBILE-START -->
   $CMS_RENDER(template:"sfcc_language_dropdown", mobile:true)$
<!-- CMS-LANGUAGE-DROPDOWN-MOBILE-END -->

The Language Dropdown format template first determines the language currently displayed in the preview and shows this along with the corresponding icon as the first entry in the dropdown or language menu. The list of all languages contained within the project is then queried and made available as further selection options with the exception of the previously defined language.

The editorial content maintained on the FirstSpirit side contains links which can be used to link content. In addition, links can be used to provide documents for download or for contact details.

These are based on different link templates, which are described in detail in the following sub-chapters.

$CMS_IF(lt_linkTags)$
   <a href="$CMS_VALUE(lt_url)$"
    $CMS_IF(!lt_linktext.isEmpty)$ title="$CMS_VALUE(lt_linktext)$"$CMS_END_IF$
    target="_blank">
      $CMS_VALUE(lt_linktext, default: "Link")$
   </a>
$CMS_ELSE$
   href="$CMS_VALUE(lt_url)$"
   $CMS_IF(!lt_linktext.isEmpty)$ title="$CMS_VALUE(lt_linktext)$"$CMS_END_IF$
   target="_blank"
$CMS_END_IF$

Within the supplied reference project ContentConnect Reference Project, assets are represented by sections. Depending on the use case, they each have a slot configuration, which makes it possible to deliver editorial content in a way which is specific to the target group and tailored to the customer.

Editor view
The option to configure a slot is provided to an editor in the reference project in the form of an input component. It is included in the sections available to the editor and may include a maximum of one single slot configuration.

The slot configuration can be (de)activated by the editor and selected as the default configuration for the associated slot. In addition, it makes it possible to define the schedule parameters known from Salesforce. By adding several sections of the same type (e.g., several sliders) but which have different slot configurations, it is possible to implement different types of content.

Developer view
An individual slot configuration is represented by the SFCC Slot Configuration link template, which is used within the following sections of the Slot Configuration input component:

Within the HTML channel of the link template, the XML expected by Commerce Cloud is created in line with the configuration defined by the editor and written in the collector provided. The XML is transferred to Commerce Cloud using a deployment.

Content is released, deleted, and deployed within the supplied reference project ContentConnect Reference Project via workflows. For this reason, it contains a publish workflow, as well as the BasicWorkflows.

Editor view
The BasicWorkflows provide an editor with the option to release modified content and to remove FirstSpirit elements both from the Current State and the Release State. Both workflows are based on the four-eyes principle and are always executed in the context of a page. If a conflict arises while a workflow is running, the workflow can be continued once the conflict has been rectified.

The publish workflow is available to editors to synchronize changes made in the FirstSpirit project on the Salesforce side. It initiates the deployment schedule and is therefore executed without any context. For this reason, it is started in ContentCreator via the Actions menu and in SiteArchitect via the Task list. The deployment schedule transfers all released content to Commerce Cloud and triggers the deletion of assets and slot configurations, which have been removed in FirstSpirit, on the Salesforce side.

Figure 39. Publish workflow in ContentCreator

Developer view
The release workflow and the delete workflow correspond to those of the BasicWorkflow module and have not been changed. The release workflow is oriented towards the administrative direct release and provides its functionality for the editor. The delete workflow makes it possible to remove elements from the Current State and the Release State.

To transfer the changes made in the FirstSpirit project, the publish workflow has also been added to the reference project. Using the SFCC Release Deployment script, this determines the deployment schedule and executes it. Unlike the other two workflows, it does not refer explicitly to one single page. For this reason, the option Workflow executable without context is activated in its Properties.

Figure 40. Publish workflow options